CHECK_MATH
The CHECK_MATH function returns and clears the accumulated math error status.
Examples
To check and clear the accumulated math error status using all the defaults, enter:
PRINT, CHECK_MATH()
IDL prints the accumulated math error status code and resets to zero.
For more examples, please see Additional Examples near the bottom of this topic.
Syntax
Result = CHECK_MATH( [, MASK=bitmask] [, /NOCLEAR] [, /PRINT] )
Return Value
The returned value is the sum of the bit values (described in the following table) of the accumulated errors.
|
Value |
Condition |
|
0 |
No errors detected since the last interactive prompt or call to CHECK_MATH |
|
1 |
Integer divided by zero |
|
2 |
Integer overflow |
|
16 |
Floating-point divided by zero |
|
32 |
Floating-point underflow |
|
64 |
Floating-point overflow |
|
128 |
Floating-point operand error. An illegal operand was encountered, such as a negative operand to the SQRT or ALOG functions, or an attempt to convert to integer a number whose absolute value is greater than 231 - 1 |
Note: CHECK_MATH can only relay information reported by the underlying hardware. Some hardware/operating system combinations may not report all of the math errors listed.
Each type of error is only represented once in the return value—any number of “Integer divided by zero” errors will result in a return value of 1.
The math error status is cleared (reset to zero) when CHECK_MATH is called, or when errors are reported. Math errors are reported either never, when the interpreter returns to an interactive prompt, or after execution of each IDL statement, depending on the value of the !EXCEPT system variable (see !EXCEPT). See Examples below for further discussion.
Keywords
MASK
If present, the mask of exceptions to check. Otherwise, all exceptions are checked. Exceptions that are pending but not specified by MASK are not reported, and not cleared. Set this keyword equal to the sum of the bit values for each exception to be checked.
NOCLEAR
By default, CHECK_MATH returns the pending exceptions (as specified via the MASK keyword) and clears them from its list of pending exceptions. If NOCLEAR is set, the exceptions are not cleared and remain pending.
Set this keyword to print an error message to the IDL command log if any accumulated math errors exist. If this keyword is not present, CHECK_MATH executes silently.
Additional Examples
CHECK_MATH and !EXCEPT
Because the accumulated math error status is cleared when it is reported, the behavior and appropriate use of CHECK_MATH depends on the value of the system variable !EXCEPT.
- If !EXCEPT is set equal to 0, math exceptions are not reported automatically, and thus CHECK_MATH will always return the error status accumulated since the last time it was called.
- If !EXCEPT is set equal to 1, math exceptions are reported when IDL returns to the interactive command prompt. In this case, CHECK_MATH will return appropriate error codes when used within an IDL procedure, but will always return zero when called at the IDL prompt.
- If !EXCEPT is set equal to 2, math exceptions are reported after each IDL statement. In this case, CHECK_MATH will return appropriate error codes only when used within an IDL statement, and will always return zero otherwise.
For example, if !EXCEPT is set equal to zero and we cause both floating-point and integer math errors:
!EXCEPT=0
PRINT, 1./0., 1/0
IDL prints:
Inf 1
The special floating-point value Inf is returned for 1./0. There is no integer analogue to the floating-point Inf. If we check the accumulated error status:
PRINT, CHECK_MATH()
IDL prints:
17
CHECK_MATH reports floating-point and integer divide-by-zero errors.
If !EXCEPT is set equal to one and we cause both floating-point and integer math errors:
!EXCEPT=1
PRINT, 1./0., 1/0
IDL prints:
Inf 1
% Program caused arithmetic error: Integer divide by 0
% Program caused arithmetic error: Floating divide by 0
This time IDL also prints error messages when returning to the command prompt. If we check the accumulated error status:
PRINT, CHECK_MATH()
IDL prints:
0
because the status was reset.
However, if we do not allow IDL to return to an interactive prompt before checking the math error status:
!EXCEPT=1
PRINT, 1./0., 1/0 & PRINT, CHECK_MATH()
IDL prints:
Inf 1
17
In this case, the math error status code (17) is printed, but because the error status has been cleared by the call to CHECK_MATH, no error messages are printed when IDL returns to the interactive command prompt.
Finally, if !EXCEPT is set equal to two and we cause both floating-point and integer math errors:
!EXCEPT=2
PRINT, 1./0., 1/0 & PRINT, CHECK_MATH()
IDL prints:
Inf 1
% Program caused arithmetic error: Integer divide by 0
% Program caused arithmetic error: Floating divide by 0
% Detected at $MAIN$
0
In this case, errors are printed before executing the CHECK_MATH function, so CHECK_MATH reports no errors. However, if we include the call to CHECK_MATH in the first PRINT command, we see the following:
PRINT, 1./0., 1/0, CHECK_MATH()
IDL prints:
Inf 1 17
Printing Error Messages
The following code fragment prints abbreviated names of errors that have occurred:
;Create a string array of error names.
ERRS = ['Divide by 0', 'Underflow', 'Overflow', $
'Illegal Operand']
;Get math error status.
J = CHECK_MATH()
FOR I = 4, 7 DO IF ISHFT(J, -I) AND 1 THEN $
;Check to see if an error occurred and print the
;corresponding error message.
PRINT, ERRS(I-4), ' Occurred'
Testing Critical Code
Example 1
Assume you have a critical section of code that is likely to produce an error. The following example shows how to check for errors, and if one is detected, how to repeat the code with different parameters.
; Clear error status from previous operations, and print error
; messages if an error exists:
JUNK = CHECK_MATH(/PRINT)
; Disable automatic printing of subsequent math errors:
!EXCEPT=0
;Critical section goes here.
AGAIN: ...
; Did an arithmetic error occur? If so, print error message and
; request new values:
IF CHECK_MATH() NE 0 THEN BEGIN
PRINT, 'Math error occurred in critical section.'
; Get new parameters from user:
READ, 'Enter new values.',...
; Enable automatic printing of math errors:
!EXCEPT=2
;And retry:
GOTO, AGAIN
ENDIF
Example 2
This example demonstrates the use of the MASK keyword to check for a specific error, and the NOCLEAR keyword to prevent exceptions from being cleared:
PRO EXAMPLE2_CHECKMATH
!EXCEPT=0
PRINT, 1./0
PRINT, CHECK_MATH(MASK=16,/NOCLEAR)
PRINT, CHECK_MATH(MASK=2,/NOCLEAR)
END
IDL prints:
Inf
16
0
% Program caused arithmetic error: Floating divide by 0
Version History
|
Original |
Introduced |